---
{
	"title": "Overlay",
	"language": "en",
	"category": "Plugins",
	"categoryfile": "plugins",
	"description": "A flexible, responsive overlay plugin.",
	"altLangPrefix": "overlay",
	"dateModified": "2014-08-06"
}
---
<span class="wb-prettify all-pre hide"></span>

<section>
	<h2>Purpose</h2>
	<p>A flexible, responsive overlay plugin. Implements the <a href="https://www.w3.org/TR/wai-aria-practices/#dialog_modal">WAI-ARIA Dialog (Modal) design pattern</a>.</p>
</section>

<section>
	<h2>Working example</h2>
	<ul>
		<li><a href="../../../demos/overlay/overlay-en.html">English example</a></li>
		<li><a href="../../../demos/overlay/overlay-fr.html">French example</a></li>
	</ul>
</section>

<section>
	<h2>Evaluation and report</h2>
	<ul>
		<li>Accessibility assessment
			<ul>
				<li><a href="../../../demos/overlay/reports/1-a11y-en.html">English report</a></li>
				<li><a href="../../../demos/overlay/reports/1-a11y-fr.html" hreflang="fr">French report</a></li>
			</ul>
		</li>
		<li>Accessibility Conformance Report
			<ul>
				<li><a href="../../../demos/overlay/reports/1-acr-wcag21-en.html">English report</a></li>
				<li><a href="../../../demos/overlay/reports/1-acr-wcag21-fr.html" hreflang="fr">French report</a></li>
			</ul>
		</li>
	</ul>
</section>

<section>
	<h2>How to implement</h2>
	<p>For centred popups, please see the <a href="../lightbox/lightbox-en.html">Lightbox documentation</a>.</p>
	<ol>
		<li>
			<p>Create a <code>section</code> element with a unique id and the following classes <code>wb-overlay modal-content overlay-def</code>.</p>
			<pre><code>&lt;section id="unique-id" class="wb-overlay modal-content overlay-def wb-bar-t"&gt;&lt;/section&gt;</code></pre>
		</li>
		<li>
			<p>Add one of the following classes to the section element to configure the type of overlay:</p>
			<ul>
				<li><code>wb-panel-l</code>: Left panel</li>
				<li><code>wb-panel-r</code>: Right panel</li>
				<li><code>wb-bar-t</code>: Top bar</li>
				<li><code>wb-bar-b</code>: Bottom bar</li>
				<li><code>wb-popup-mid</code>: Middle screen overlay</li>
				<li><code>wb-popup-full</code>: Full-screen overlay</li>
				<li><code>wb-popup-full hidden-hd</code>: Full-screen overlay - Hidden header</li>
			</ul>
		</li>
		<li>
			<p>Add the header of the overlay by adding the following code at the start of the section element:</p>
			<pre><code>&lt;header class=&quot;modal-header&quot;&gt;
	&lt;h2 class=&quot;modal-title&quot;&gt;Overlay title&lt;/h2&gt;
&lt;/header&gt;</code></pre>
			<p>For the full-screen overlay with a hidden header, use the following instead:</p>
			<pre><code>&lt;header&gt;
	&lt;h2 class=&quot;wb-inv&quot;&gt;Overlay title&lt;/h2&gt;
&lt;/header&gt;</code></pre>
		</li>
		<li>
			<p>Add the body of the overlay by adding the following code after the header code:</p>
			<pre><code>&lt;div class=&quot;modal-body&quot;&gt;
	... Overlay content ...
&lt;/div&gt;</code></pre>
		</li>
		<li>
			<p>Add a way of opening the overlay. The overlay can be opened either by clicking a link or by triggering an event.</p>
			<ul>
				<li>
					<p><strong>Link approach:</strong> Add the following link to the page where the <code>href</code> and the <code>aria-controls</code> attribute match the <code>id</code> attribute on the <code>section</code> element of the overlay:</p>
					<pre><code>&lt;li&gt;
	&lt;a href=&quot;#unique-id&quot; aria-controls=&quot;unique-id&quot; class=&quot;overlay-lnk&quot; role=&quot;button&quot;&gt;Open overlay&lt;/a&gt;
&lt;/li&gt;</code></pre>
				</li>
				<li>
					<p><strong>Event approach:</strong> Trigger the overlay with the following JavaScript code:</p>
					<pre><code>$( "#unique-id" ).trigger( "open.wb-overlay" );</code></pre>
				</li>
			</ul>
		</li>
	</ol>
</section>

<section>
	<h2>Configuration options</h2>
	<table class="table">
		<thead>
			<tr>
				<th>Option</th>
				<th>Description</th>
				<th>How to configure</th>
				<th>Values</th>
			</tr>
		</thead>
		<tbody>
			<tr>
				<td>Overlay type</td>
				<td>Configure the type of overlay to display.</td>
				<td>Add the configuration class to the <code>&lt;section&gt;</code> element of the overlay.</td>
				<td>
					<dl>
						<dt><code>wb-panel-l</code>:</dt>
						<dd>Left panel</dd>
						<dt><code>wb-panel-r</code>:</dt>
						<dd>Right panel</dd>
						<dt><code>wb-bar-t</code>:</dt>
						<dd>Top bar</dd>
						<dt><code>wb-bar-b</code>:</dt>
						<dd>Bottom bar</dd>
						<dt><code>wb-popup-mid</code>:</dt>
						<dd>Middle screen overlay</dd>
						<dt><code>wb-popup-full</code>:</dt>
						<dd>Full-screen overlay</dd>
					</dl>
				</td>
			</tr>
			<tr>
				<td>No print</td>
				<td>Hide the opened overlay when printing.</td>
				<td>Only work for left panel, right panel, top bar and bottom bar. Add the class <code>no-print</code> to the <code>&lt;section&gt;</code> element of the overlay.</td>
				<td><code>no-print</code></td>
			</tr>
			<tr>
				<td>Add an overlay background</td>
				<td>Stand up the overlay dialog by adding a black overlay background.</td>
				<td>To be used with middle overlay.</td>
				<td><code>overlay-bg</code></td>
			</tr>
		</tbody>
	</table>
</section>

<section>
	<h2>Events</h2>
	<table class="table">
		<thead>
			<tr>
				<th>Event</th>
				<th>Trigger</th>
				<th>What it does</th>
			</tr>
		</thead>
		<tbody>
			<tr>
				<td><code>wb-init.wb-overlay</code></td>
				<td>Triggered manually (e.g., <code>$( ".wb-overlay" ).trigger( "wb-init.wb-overlay" );</code>).</td>
				<td>Used to manually initialize the Overlay plugin. <strong>Note:</strong> The Overlay plugin will be initialized automatically unless the required markup is added after the page has already loaded.</td>
			</tr>
			<tr>
				<td><code>wb-ready.wb-overlay</code> (v4.0.5+)</td>
				<td>Triggered automatically after an overlay is initialized.</td>
				<td>Used to identify when an overlay has initialized (target of the event)
					<pre><code>$( document ).on( "wb-ready.wb-overlay", ".wb-overlay", function( event ) {
});</code></pre>
					<pre><code>$( ".wb-overlay" ).on( "wb-ready.wb-overlay", function( event ) {
});</code></pre>
				</td>
			</tr>
			<tr>
				<td><code>open.wb-overlay</code></td>
				<td>Triggered manually (e.g., <code>$( ".wb-overlay" ).trigger( "open.wb-overlay" );</code>).</td>
				<td>Used to manually open an overlay (event must be triggered on the <code>section</code> element of the overlay).</td>
			</tr>
			<tr>
				<td><code>opened.wb-overlay</code></td>
				<td>Triggered automatically after an overlay is open.</td>
				<td>Used to identify when an overlay has been opened (target of the event)
					<pre><code>$( document ).on( "opened.wb-overlay", ".wb-overlay", function( event ) {
});</code></pre>
					<pre><code>$( ".wb-overlay" ).on( "opened.wb-overlay", function( event ) {
});</code></pre>
				</td>
			</tr>
			<tr>
				<td><code>close.wb-overlay</code></td>
				<td>Triggered manually (e.g., <code>$( ".wb-overlay" ).trigger( "close.wb-overlay" );</code>).</td>
				<td>Used to manually close an overlay (event must be triggered on the <code>section</code> element of the overlay).</td>
			</tr>
			<tr>
				<td><code>closed.wb-overlay</code></td>
				<td>Triggered automatically after an overlay is close.</td>
				<td>Used to identify when an overlay has been closed (target of the event)
					<pre><code>$( document ).on( "closed.wb-overlay", ".wb-overlay", function( event ) {
});</code></pre>
					<pre><code>$( ".wb-overlay" ).on( "closed.wb-overlay", function( event ) {
});</code></pre>
				</td>
			</tr>
			<tr>
				<td><code>wb-ready.wb</code> (v4.0.5+)</td>
				<td>Triggered automatically when WET has finished loading and executing.</td>
				<td>Used to identify when all WET plugins and polyfills have finished loading and executing.
					<pre><code>$( document ).on( "wb-ready.wb", function( event ) {
});</code></pre>
				</td>
			</tr>
		</tbody>
	</table>
</section>

<section>
	<h2>Source code</h2>
	<p><a href="https://github.com/wet-boew/wet-boew/tree/master/src/plugins/overlay">Overlay plugin source code on GitHub</a></p>
</section>
